feat: migrate from Python Claude Agent SDK to Vercel AI SDK v6 (TypeScript) by AndyMik90 · Pull Request #1891 · AndyMik90/Aperant

AndyMik90 · 2026-02-22T15:13:38Z

Summary

Complete migration of all AI agent execution from Python claude-agent-sdk subprocess calls to a native TypeScript agent layer using Vercel AI SDK v6 (ai package)
190+ new TypeScript files in apps/frontend/src/main/ai/ implementing providers, tools, security, orchestration, runners, memory, and MCP integration
Zero Python subprocess calls remain in production IPC handlers — the backend is reduced to Graphiti memory sidecar + CLI utilities
Local-first memory system using libSQL (Turso) with embedding-based retrieval, replacing the external Graphiti dependency for core memory operations

What changed

Provider Layer (ai/providers/)

Multi-provider registry supporting 9 providers: Anthropic, OpenAI, Google, Bedrock, Azure, Mistral, Groq, xAI, Ollama
OAuth token detection (sk-ant-oa* / sk-ant-ort*) with automatic refresh
Provider-specific transforms for thinking token normalization and prompt caching

Session Runtime (ai/session/)

runAgentSession() using streamText() with stopWhen: stepCountIs(N) for agentic tool-use loops
Error classification (429 rate-limit, 401 auth, 400 bad-request) with automatic retry
Structured progress tracking from tool calls and text patterns

Worker Threads (ai/agent/)

Agent sessions run in worker_threads to avoid blocking the Electron main process
WorkerBridge relays postMessage() events to the existing AgentManagerEvents interface
SerializableSessionConfig crosses thread boundary; LanguageModel recreated in worker

Build Orchestration (ai/orchestration/)

Full planner → coder → QA pipeline ported from Python
Spec validator, conversation compactor, QA reports, pause handler
Parallel subagent execution via Promise.allSettled()

Tools (ai/tools/)

8 builtin tools (Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch) with Zod schemas
6 Auto Claude custom tools (record_gotcha, get_session_context, etc.)
Tool registry with per-agent-type tool filtering

Security (ai/security/)

19 validators + secret scanner + tool input validator
Bash command parser and validator with identical allowlist behavior to Python
Path containment for filesystem boundary enforcement

Memory System (ai/memory/)

Local libSQL database with WAL mode, FTS5 full-text search, and vector embeddings
Embedding service with auto-detection (Ollama local, OpenAI cloud fallback)
Reranker, retrieval pipeline, and memory-aware context injection
16 memory types across 6 categories (patterns, errors, decisions, insights, calibration)
UI: Memory browser with category filters, health metrics, search, and expandable cards

Runners (ai/runners/)

Insights, roadmap, ideation, commit-message, changelog runners
GitHub PR review engine, triage engine, batch processor, bot detector
GitLab MR review engine

IPC Handlers Rewired

pr-handlers, mr-review-handlers, autofix-handlers, triage-handlers, insights-executor all call TypeScript runners directly instead of spawning Python subprocesses

Other

Worktree manager ported to TypeScript
Project analyzer, stack detector, framework detector, command registry (400+ commands)
Context builder with keyword extraction, service matching, categorization
Semantic merge analyzer with 80+ conflict detection rules and 8 merge strategies
electron-vite config updated for worker thread entry points and AI SDK bundling

Verification

0 TypeScript errors (tsc --noEmit)
3,869 tests passing (164 test files), 0 failures
electron-vite build clean
E2E tested via Electron MCP: memory system connects, renders memories, filters work, no console errors

Test plan

TypeScript compilation: cd apps/frontend && npx tsc --noEmit — 0 errors
Unit tests: cd apps/frontend && npm test — 3,869 passed
Build: cd apps/frontend && npx electron-vite build — clean
E2E: Memory panel renders, filters, health metrics, card expansion all verified via Electron MCP screenshots
Full agent task execution (spec → build → QA) in desktop app
Cross-platform verification (Windows, Linux)

🤖 Generated with Claude Code

…der packages Added dependencies: ai@^6, @ai-sdk/anthropic, @ai-sdk/openai, @ai-sdk/google, @ai-sdk/amazon-bedrock, @ai-sdk/azure, @ai-sdk/mistral, @ai-sdk/groq, @ai-sdk/xai, @ai-sdk/openai-compatible, @ai-sdk/mcp, @modelcontextprotocol/sdk. Verified zod/v3 compat works with existing zod v4. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Define SupportedProvider enum, ProviderConfig, ModelResolution, and ProviderCapabilities types. Port MODEL_ID_MAP, THINKING_BUDGET_MAP, MODEL_BETAS_MAP, and phase config types from phase_config.py. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…onfig) → LanguageModel Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…iderRegistry Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Port thinking token normalization, tool ID format transforms, prompt caching thresholds, and adaptive thinking support from phase_config.py. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ty/parser Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ty/hooks. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

… boundary Add path-containment.ts with assertPathContained() for filesystem boundary enforcement including symlink resolution, traversal prevention, and cross-platform normalization. Add security-profile.ts for loading and caching project security profiles from .auto-claude config files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…security layer Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Define ToolContext interface (cwd, projectDir, specDir, securityProfile), ToolPermission types, ToolExecutionOptions, and ToolDefinitionConfig. Create Tool.define() that wraps AI SDK v6 tool() with Zod v3 inputSchema and security hooks integration (bash validator pre-execution check). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…dit, Glob) Implements Read (line offset/limit, image base64, PDF support), Write (content validation, mkdir -p), Edit (exact string replacement, replace_all), and Glob (fs.globSync, mtime sort) with Zod schemas and path-containment security integration. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add the 4 remaining built-in tools following the existing Tool.define() pattern: - Bash: command execution with bashSecurityHook() integration, timeout, background support - Grep: ripgrep-based search with output modes, file type/glob filtering - WebFetch: URL fetching with timeout and content truncation - WebSearch: web search with domain allow/block list filtering Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ig registry Port tool constants (BASE_READ_TOOLS, BASE_WRITE_TOOLS, WEB_TOOLS), MCP tool lists, and AGENT_CONFIGS from Python models.py. Implement ToolRegistry with registerTool(), getToolsForAgent(), and helper functions getAgentConfig(), getDefaultThinkingLevel(), getRequiredMcpServers(). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…t-configs.ts Port all 27 agent type configurations from Python backend to TypeScript. Includes tool lists, MCP server mappings, auto-claude tools, thinking defaults, and helper functions (getAgentConfig, getRequiredMcpServers, getDefaultThinkingLevel, mapMcpServerName). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…lback chain Add auth types and resolver that reuses existing claude-profile/credential-utils.ts. Implements 4-stage fallback: profile OAuth token → profile API key → environment variable → default provider credentials. Supports all providers with provider-specific env var mappings. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add MCP integration layer using @ai-sdk/mcp with @modelcontextprotocol/sdk for stdio/StreamableHTTP transports. Define server configs for context7, linear, graphiti, electron, puppeteer, auto-claude. Implement getMcpServersForAgent() via createMcpClientsForAgent() with dynamic server resolution and graceful fallback on connection failures. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…, and transforms Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…g, and tool registry Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add SessionConfig, SessionResult, StreamEvent, ProgressState types for the agent session runtime. Add AgentClientConfig/Result and SimpleClientConfig/Result types for the client layer. Implement createAgentClient() with full tool/MCP setup and createSimpleClient() for utility runners with minimal tools. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add stream-handler.ts to process AI SDK v6 fullStream events (text-delta, reasoning, tool-call, tool-result, step-finish, error) and emit structured StreamEvents. Add error-classifier.ts ported from Python core/error_utils.py with classification for rate limit (429), auth failure (401), concurrency (400), tool execution, and abort errors. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…tion from tool calls + text patterns Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ssion(). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add 78 tests across 4 test files covering: - stream-handler: text-delta, reasoning, tool-call/result, step-finish, error, multi-step conversations - error-classifier: 429/401/400 detection, abort errors, classification priority, sanitization - progress-tracker: phase detection from tools/text, regression prevention, terminal locking - runner: completion, max_steps, auth retry, cancellation, event forwarding, tool tracking Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…orker bridge Add the worker thread infrastructure for running AI agent sessions off the main Electron thread: - executor.ts: AgentExecutor class wrapping WorkerBridge with start/stop/retry - worker.ts: Worker thread entry point receiving config via workerData, running runAgentSession(), posting structured messages back via parentPort - worker-bridge.ts: Main-thread bridge spawning Worker, relaying postMessage events to EventEmitter matching AgentManagerEvents interface - types.ts: WorkerConfig, SerializableSessionConfig, WorkerMessage protocol Handles dev/production Electron paths, SecurityProfile serialization across worker boundaries, and abort signal propagation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…sManager Replace Python subprocess spawn with Worker thread creation for AI SDK agents. Add spawnWorkerProcess() using WorkerBridge for postMessage event handling. Update killProcess/killAllProcesses to handle Worker thread termination. Add optional worker field to AgentProcess interface. Keep spawnProcess() and getPythonPath()/ensurePythonEnvReady() for backward compatibility. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…AgentEvents Add handleStructuredProgress() and buildProgressData() methods that accept typed progress events from worker threads via postMessage, bypassing text matching. Includes phase regression prevention. Existing parseExecutionPhase() preserved as fallback for backward compatibility during transition. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Tests cover: worker spawning, message relay (log/error/progress/stream-event), result handling with exit code mapping, crash handling (worker error/exit events), termination with abort signal, executor lifecycle (start/stop/retry), config management, and AgentManagerEvents compatibility. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…terator.ts Replaces Python run.py main build loop and agents/coder.py subtask iteration with TypeScript equivalents for the Vercel AI SDK migration. - BuildOrchestrator: drives planning → coding → qa_review → qa_fixing → complete - SubtaskIterator: reads implementation_plan.json, iterates pending subtasks - Phase transitions validated via phase-protocol.ts - Retry tracking, stuck detection, abort signal support Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-advanced-security

CodeQL found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

- Increase polling interval from 30s to 60s for active profile - Increase inactive profile cache TTL from 60s to 5 minutes - Add adaptive cache: drops to 60s when active usage >80% session or >90% weekly - Add request coalescing for getAllProfilesUsage() to prevent duplicate fetches - Stagger same-provider fetches with 15s delay (prevents burst-hitting same API) - Add 10-minute backoff for 429 rate limits (vs 2min general failure cooldown) - Stop force-refreshing on AccountSettings open (use cached data + push updates) - Fix false "needs re-auth" flag: clear needsReauthProfiles when valid token obtained - Remove noisy ProjectStore subtask completion diagnostic logging Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

sentry · 2026-03-09T09:29:18Z

🚧 Skipped: PR exceeds review size limit.

Please split into smaller PRs and re-run.
_{Reference ID: 11396101}

sentry · 2026-03-09T11:19:07Z

🚧 Skipped: PR exceeds review size limit.

Please split into smaller PRs and re-run.
_{Reference ID: 11402351}

sentry · 2026-03-09T12:57:29Z

🚧 Skipped: PR exceeds review size limit.

Please split into smaller PRs and re-run.
_{Reference ID: 11407737}

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

CLAUDE.md

sentry · 2026-03-09T21:16:29Z

🚧 Skipped: PR exceeds review size limit.

Please split into smaller PRs and re-run.
_{Reference ID: 11444614}

sentry · 2026-03-11T13:50:46Z

🚧 Skipped: PR exceeds review size limit.

Please split into smaller PRs and re-run.
_{Reference ID: 11562797}

sentry · 2026-03-11T17:13:05Z

🚧 Skipped: PR exceeds review size limit.

Please split into smaller PRs and re-run.
_{Reference ID: 11578834}

…python-to-vercel-ai-sdk-t

sentry · 2026-03-11T17:40:33Z

🚧 Skipped: PR exceeds review size limit.

Please split into smaller PRs and re-run.
_{Reference ID: 11580739}

Address 60+ CodeQL security findings blocking PR merge: - Insecure temp files: use mkdtempSync + atomic write-rename (26 alerts) - TOCTOU race conditions: replace existsSync→act with try/catch (8 alerts) - Shell injection: replace execSync with execFileSync + args array (1 alert) - Network data validation: add type checks before disk writes (10 alerts) - File data in requests: validate tokens/credentials before use (6 alerts) - Log injection: sanitize control characters before logging (3 alerts) - Incomplete string escaping: eliminate shell interpolation (1 alert) - Dead code: remove useless conditionals and assignments (5 alerts) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

sentry · 2026-03-11T18:11:32Z

🚧 Skipped: PR exceeds review size limit.

Please split into smaller PRs and re-run.
_{Reference ID: 11583108}

- read.ts: use fstat via fd for PDF size, avoid stat→readFile gap - spec-number-lock.ts: remove existsSync pre-checks, rely on atomic wx flag and direct readFileSync with ENOENT handling - settings-utils.ts: remove access() pre-check, readFile directly with catch - log-service.ts: derive sizeBytes from Buffer.byteLength of read content instead of separate statSync - roadmap.ts: serialize from in-memory data to avoid re-read gap - subtask-iterator-restamp.test.ts: use fd.stat() + fd.readFile() on same fd Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

sentry · 2026-03-11T18:28:02Z

🚧 Skipped: PR exceeds review size limit.

Please split into smaller PRs and re-run.
_{Reference ID: 11584350}

Force GitHub code scanning PR check to re-evaluate after security fixes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

sentry · 2026-03-11T20:35:49Z

🚧 Skipped: PR exceeds review size limit.

Please split into smaller PRs and re-run.
_{Reference ID: 11593411}

- read.ts: open fd once, use fstatSync + readFileSync(fd) for all paths (directory check, image, PDF, text) through a single file descriptor - roadmap.ts: read via openSync/readFileSync(fd) instead of path-based read to decouple the "check" from the subsequent writeFileSync - subtask-iterator-restamp.test.ts: use fd.stat() instead of path-based stat for mtime recording Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

sentry · 2026-03-11T20:44:21Z

🚧 Skipped: PR exceeds review size limit.

Please split into smaller PRs and re-run.
_{Reference ID: 11594051}

- roadmap.ts: atomic write via temp file + rename to break path flow - subtask-iterator-restamp.test.ts: compare content snapshots instead of stat+read (eliminates multi-operation path reuse) - bump-version.js: replace existsSync pre-checks with try/catch on read Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

sentry · 2026-03-11T20:50:31Z

🚧 Skipped: PR exceeds review size limit.

Please split into smaller PRs and re-run.
_{Reference ID: 11594506}

AndyMik90 and others added 30 commits February 19, 2026 00:44

auto-claude: subtask-0b-2 - Create provider factory: createProvider(c…

fb2f912

…onfig) → LanguageModel Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

auto-claude: subtask-0b-3 - Create provider registry using createProv…

d7bf293

…iderRegistry Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

auto-claude: subtask-0b-4 - Create per-provider transforms layer

4b207ce

Port thinking token normalization, tool ID format transforms, prompt caching thresholds, and adaptive thinking support from phase_config.py. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

auto-claude: subtask-0c-1 - Port command-parser.ts from Python securi…

a53bac0

…ty/parser Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

auto-claude: subtask-0c-2 - Port bash-validator.ts from Python securi…

eec8058

…ty/hooks. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

auto-claude: subtask-0c-4 - Write comprehensive Vitest tests for the …

83f0279

…security layer Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

auto-claude: subtask-0e-2 - Port phase-config.ts from phase_config.py

5de9d3c

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

auto-claude: subtask-0f-1 - Unit tests for provider factory, registry…

c1c1293

…, and transforms Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

auto-claude: subtask-0f-2 - Unit tests for agent configs, phase confi…

df00aa4

…g, and tool registry Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

auto-claude: subtask-1-1 - Fix unused imports in client factory

8a8285f

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

auto-claude: subtask-1-3 - Create progress-tracker.ts for phase detec…

9083e7d

…tion from tool calls + text patterns Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

auto-claude: subtask-1-4 - Create the core session runner: runAgentSe…

288ceb6

…ssion(). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-advanced-security bot found potential problems Mar 8, 2026

View reviewed changes

AndyMik90 and others added 2 commits March 9, 2026 08:32

usage+worktree+harness

363049d

AndyMik90 added 2 commits March 9, 2026 12:08

oauth+structuredoutput

a2b1466

husky fixes

fac0c4a

onboarding and memorycleanup

06a0dd2

cursor bot reviewed Mar 9, 2026

View reviewed changes

CLAUDE.md Show resolved Hide resolved

memorycleanup

dd55f37

new spec system

7830be4

fixes

5ef3d7c

Merge branch 'develop' into auto-claude/237-migrate-claude-agent-sdk-…

3cf8705

…python-to-vercel-ai-sdk-t

chore: trigger CodeQL re-evaluation

1454613

Force GitHub code scanning PR check to re-evaluate after security fixes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

AndyMik90 merged commit 75869f7 into develop Mar 11, 2026
14 checks passed

AndyMik90 deleted the auto-claude/237-migrate-claude-agent-sdk-python-to-vercel-ai-sdk-t branch March 11, 2026 20:59

Uh oh!

Conversation

AndyMik90 commented Feb 22, 2026

Summary

What changed

Verification

Test plan

Uh oh!

github-advanced-security bot left a comment

Choose a reason for hiding this comment

Uh oh!

sentry bot commented Mar 9, 2026

Uh oh!

sentry bot commented Mar 9, 2026

Uh oh!

sentry bot commented Mar 9, 2026

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sentry bot commented Mar 9, 2026

Uh oh!

sentry bot commented Mar 11, 2026

Uh oh!

sentry bot commented Mar 11, 2026

Uh oh!

sentry bot commented Mar 11, 2026

Uh oh!

sentry bot commented Mar 11, 2026

Uh oh!

sentry bot commented Mar 11, 2026

Uh oh!

sentry bot commented Mar 11, 2026

Uh oh!

sentry bot commented Mar 11, 2026

Uh oh!

sentry bot commented Mar 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants